API 停机

Zapier 认识到，您的 API 有时不可避免地会出现临时不可用情况。

为了应对这些情况，我们建议配置自定义错误响应处理，以实现以下功能：

• 向用户显示有意义且易于理解的消息
• 避免因错误率过高而禁用 Zap
• 在指定延迟后可能重新尝试该操作

1. 默认行为

当 Zap 运行遇到您的 API 返回 5xx 错误时，会抛出异常并被标记为“已停止 / 已出错”状态。这将向用户显示错误消息，允许他们重新运行该 Zap。

如果用户启用了自动重播，则出错的步骤将在预定义的计划上进行重试。只有在所有自动重播尝试均失败后，Zap 运行才会最终被标记为“已停止 / 已出错”状态。

如果过去 7 天内 Zap 运行中有 95% 被标记为“已停止 / 已出错”状态，则该 Zap 将自动暂停。Zap 将不会重新运行，直至用户手动启用。

2. 避免自动禁用 Zap

Platform CLI

在CLI中构建时，您可以利用 HTTP 中间件来实现自定义错误响应处理。

这允许您编写一个适用于整个集成的脚本，用于检测 API 的特定错误并相应处理。例如，如果 API 停机持续时间已知，您可以在 afterResponse 中间件中捕获 503 响应，并像这样抛出一个ThrottledError：

const yourAfterResponse = (resp) => {
  if (resp.status === 503) {
    throw new z.errors.ThrottledError('Service is temporarily unavailable. Retrying in 60 seconds.', 60);  // Zapier will retry in 60 seconds
  }
  return resp;
};

注意： 在调用 z.request() 时，需要将 skipThrowForStatus 设置为 true。

Platform UI

在UI中构建时，需要为集成的每个元素（包括身份验证、触发器和操作）添加自定义错误处理，使用代码模式。

例如：

const options = {
  url: `https://example.app/api/endpoint`,
  skipThrowForStatus: true,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  params: {},
  body: {}
}

return z.request(options)
  .then((response) => {
    if (response.status === 503){
      throw new z.errors.ThrottledError('Service is temporarily unavailable. Retrying in 60 seconds.', 60); // Zapier will retry in 60 seconds
    }
    const results = response.json;
    return results;
  });

注意： 使用 Zapier Platform UI 构建的集成，可以在高级/设置中启用 skipThrowForStatus 选项，以在每个请求上设置 skipThrowForStatus: true。

3. 指定 Zapier 重试前的等待时间

ThrottledError(message, delay) 方法接受两个参数：一个自定义错误消息（字符串）和一个延迟时间（以秒为单位的整数）。

在 API 停机期间，返回的响应中应包含 Retry-After 标头，以指定服务预计恢复后 Zapier 应该重试请求的时间。您的自定义错误处理脚本 可以读取此标头，并将其传递给 ThrottledError() 的延迟参数，如下所示：

if(response.status === 503){
    const delay = response.getHeader('retry-after');
    const message = `Service is temporarily unavailable. Retrying in ${delay} seconds.`;
    throw new z.errors.ThrottledError(message, delay);
}

4. 预定 API 维护

对于预定维护期，您可以根据请求在特定开始和结束时间之间将应用的（API）状态设置为“非健康”。这样，会在我们的状态页面上发布“预定维护”消息，例如示例。

该应用还会在应用状态 选项卡中显示为“非健康”状态。

在设定的维护窗口期间，受影响的 Zap 将按以下方式处理：

操作/搜索： 包含受影响操作或搜索的 Zap 运行将在 Zap 历史页面显示为“运行中”状态。该操作或搜索将延迟，直到事件解决，或最多尝试五次。在第五次尝试时，Zapier 将不顾应用状态而执行。如果失败，Zap 运行将出错，并可以使用标准手动重播机制来重播受影响的运行。

触发器：大多数 包含受影响（轮询）触发器的 Zap 不会运行，因此（在大多数情况下）Zap 历史中不会有运行记录。

更详细地说，Zapier 将“跳过”90%的轮询，只允许10%通过，因此通常有些 Zap 会触发一些运行。15 分钟后，所有轮询将被重新启用，以检查 API 是否已恢复健康。如果未恢复，Zapier 将再次“跳过”90%的轮询。此过程将重复，直到 API 恢复健康。一旦 API 恢复健康，Zap 将被触发并补齐遗漏的数据，受正常轮询限制（如分页）的影响。

如果 Zap 运行出错，用户将根据其通知设置通过电子邮件收到通知。

如果您希望为您的应用安排维护窗口，请将以下信息发送给开发者支持：

• 开始日期和时间（UTC）
• 结束日期和时间（UTC）
• 停机期间 API 的响应细节，例如，它是否会返回HTTP 503 “服务不可用”状态代码，或完全不响应。

---